Using the API via XMPP

As you may know, Fanout Cloud supports delivering data to both HTTP and XMPP clients/endpoints. What you may not know is that the Fanout Cloud API itself is accessible via both protocols, too. This means that not only can you publish messages or make configuration changes via REST, you can perform these same tasks by sending XMPP stanzas. Why would you want to do this? Well, in certain cases, XMPP may be a more convenient or more optimal way of accessing the Fanout Cloud API. Additionally, the fact that you can use the API via one protocol but publish data to an endpoint of the opposite protocol allows for crossover possibilities. For example, you can use the REST API to fire off XMPP stanzas, or use XMPP ad-hoc commands to stream data to HTTP clients.

Using the XMPP API is easy. First, you whitelist the JIDs that should have access. Then, those JIDs are able to make calls. The reason for the whitelist is that, unlike the REST API, authentication tokens are not needed with XMPP. Instead, the authorized entities are configured in advance and authentication is implied.

Setting things up

There are several ways to give a JID access to the API. The simplest way is to provide a JID in your Fanout Account Settings:

Alternatively, you can add any number of JIDs as admins using the REST API. More on that here. Of course, you’ll need an authentication token to make this request. If you’re feeling particularly lazy, you can obtain a token by going to your realm’s test page within the Fanout Control Panel and copying it out of the example curl command at the bottom.

You can even add admin JIDs via the XMPP API by providing an authentication token in the request in lieu of being whitelisted. Send admin-add --token {token} {jid} as the body of a message stanza to the JID admin-{realm}@api.fanout.io, with {token} {jid} and {realm} substituted with the obvious.

Using the API

Now that your JID is whitelisted, the fun begins. To try out the chatbot interface, add the JID admin-{realm}@api.fanout.io to your buddy list (with {realm} substituted with your realm). It should accept your request and appear as an online contact. Open a chat window and send the word “help” to it, to see the list of available commands.

For example, if you go to the Fanout Control Panel and open up a test page for one of your domains, you can push data to it like this:

The API is also available as ad-hoc commands. If you’ve got an ad-hoc commands capable client, such as Psi, then you can browse available commands and invoke them via a GUI. Start by querying for the commands of the JID api.fanout.io and go from there:

For example, here we are setting up a webhook subscription using a handy form:

That’s all there is to it! We hope you enjoy the availablity of XMPP as a first class citizen within the Fanout Cloud API.